package com.hnit.service;
import com.hnit.web.DTO.CartDTO;
import com.hnit.web.DTO.ProductDTO;

import java.util.List;

/**
 * @author 嘿嘿
 * @description 购物车服务接口
 * @date 2025-08-01
 */
public interface CartService {

    /**
     * 将商品添加到指定用户的购物车.
     * <p>
     * 如果该商品已存在于用户的购物车中，则更新其数量；
     * 如果不存在，则新增一条购物车记录。
     *
     * @param userId    用户ID，用于标识是哪个用户的购物车
     * @param productId 商品ID，要添加到购物车的商品
     * @param quantity  要添加的数量
     */
    CartDTO addItemToCart(Long userId, Long productId, Integer quantity);

    /**
     * 获取指定用户购物车中的所有商品列表.
     * <p>
     * 返回的是CartDTO列表，其中包含了详细的商品信息（如商品名、价格、图片等），
     * 以便在前端页面进行展示。
     *
     * @param userId 用户ID
     * @return 包含购物车商品详细信息的 DTO 列表
     */
    List<CartDTO> listCartItems(Long userId);

    /**
     * 更新购物车中某条记录的商品数量.
     *
     * @param cartId   购物车的唯一ID
     * @param quantity 更新后的新数量
     */
    boolean updateItemQuantity(Long cartId, Integer quantity);

    /**
     * 从购物车中移除单个商品.
     *
     * @param cartId 要移除的购物车记录的唯一ID
     */
    boolean removeItemFromCart(Long cartId);

    /**
     * 批量从购物车中移除多个商品.
     *
     * @param cartIds 要移除的购物车记录ID的列表
     */
    boolean removeItemsFromCart(List<Long> cartIds);

    /**
     * 清空指定用户的所有购物车项.
     * <p>
     * 通常在用户成功下单后调用此方法。
     *
     * @param userId 用户ID
     */
    boolean clearCart(Long userId);

    /**
     * 获取用户购物车中的商品项总数（不是商品总数量）.
     * <p>
     * 例如，购物车里有2本书和3支笔，此方法返回2。
     * 通常用于在页面的购物车图标上显示角标。
     *
     * @param userId 用户ID
     * @return 购物车中的项目种类数量
     */
    Integer getCartItemCount(Long userId);
}
